home *** CD-ROM | disk | FTP | other *** search
/ The Very Best of Atari Inside / The Very Best of Atari Inside 1.iso / sharew / accs / slectric / doku / slctprog.txt < prev    next >
Encoding:
Text File  |  1992-09-02  |  10.1 KB  |  226 lines
  1.                 Programmer's Guide to Selectric™ V1.02
  2.                 --------------------------------------
  3.  
  4.                               Juli 1992
  5.  
  6.                       (c) 1992 by Oliver Scheel
  7.  
  8.              ... this guide (however) goes Freaky Deaky!
  9.  
  10.  
  11. Einleitung
  12. ----------
  13. Ja,  auch für Selectric™ gibt's einen Programmer's Guide,  der  jedoch
  14. zur  Zeit noch nicht so umfangreich ist.  Es ist mehr geplant als  bis
  15. jetzt  verwirklicht wurde,  z.B.  wird man Selectric™ irgendwann  auch
  16. ein  sog.  virtuelles Verzeichnis übergeben können,  aus dem dann  Da-
  17. teien oder Objekte ausgewählen kann.  Ich will jetzt aber nicht zuviel
  18. verraten.
  19. Der  ganze  Kram  mit der Programmierschnittstelle  ist  übrigens  auf
  20. meinem  Mist  gewachsen.  Anfragen  sind daher am besten  an  mich  zu
  21. richten.
  22.  
  23.  
  24. Die Möglichkeiten
  25. -----------------
  26. Ich  versuche  hier  mal  kurz die  Möglichkeiten  mit  Selectric™  zu
  27. umreißen, um so einen kleinen Überblick zu verschaffen:
  28. Selectric™  installiert  einen  Cookie-Jar über  den  die  Applikation
  29. Einstellungen  vornehmen  kann.  Das schließt nicht nur  die  Optionen
  30. oder  die  Sortierung  ein,  sondern auch die  Preset-Paths  und  -Ex-
  31. tensions.  Die  Struktur wurde in diesem Fall sehr flexibel  gestaltet
  32. und sieht auf den ersten Blick etwas kompliziert aus.  Weiterhin  kann
  33. man sich auch mehr als nur einen Dateinamen zurückgeben  lassen.  Auch
  34. dies geschieht über den Cookie-Jar.
  35.  
  36. Der Cookie-Jar
  37. --------------
  38. Selectric™ legt einen sog.  `FSEL'-Cookie an. Dieser zeigt an, daß man
  39. in jedem Fall fsel_exinput() aufrufen kann,  auch wenn der neue  File-
  40. Selector  abgeschaltet  wurde.  Der Inhalt  `FSEL'-Cookies  ist  nicht
  41. festgelegt, bei Selectric™ zeigt er auf die folgende Struktur:
  42.  
  43. typedef struct
  44. {
  45.      unsigned long   id;           /* Selectric ID (`SLCT')      */
  46.      unsigned int    version;      /* version (BCD-Format)       */
  47.      struct
  48.      {
  49.           unsigned        : 8;     /* reserved                   */
  50.           unsigned pthsav : 1;     /* save and restore paths     */
  51.           unsigned stdest : 1;     /* stay in destination path   */
  52.           unsigned autloc : 1;     /* auto-locator               */
  53.           unsigned numsrt : 1;     /* numsort                    */
  54.           unsigned lower  : 1;     /* use lowercase letters      */
  55.           unsigned dclick : 1;     /* open folder on dclick      */
  56.           unsigned hidden : 1;     /* show hidden files          */
  57.           unsigned onoff  : 1;     /* Selectric™ ON/OFF          */
  58.      } config;
  59.      int       sort;               /* sort-mode (neg. = rev.)    */
  60.      int       num_ext;            /* number of extensions       */
  61.      char      *(*ext)[];          /* preset extensions          */
  62.      int       num_paths;          /* number of paths            */
  63.      char      *(*paths)[];        /* preset paths               */
  64.      int       comm;               /* communication word         */
  65.      int       in_count;           /* input counter              */
  66.      void      *in_ptr;            /* input pointer              */
  67.      int       out_count;          /* output counter             */
  68.      void      *out_ptr;           /* output pointer             */
  69.      int       cdecl     (*get_first)(DTA *dta, int attrib);
  70.      int       cdecl     (*get_next)(DTA *dta);
  71.      int       cdecl     (*release_dir)(void);
  72. } SLCT_STR;
  73.  
  74.  
  75. Fangen wir mal an:
  76.  
  77. id             Das ist die ID von Selectric™,  also `SLCT'.  Es reicht
  78.                also  nicht nur den  `FSEL'-Cookie  abzfragen,  sondern
  79.                muß zusätzlich nich die ID checken.
  80.  
  81. version        Hier  steht  die  Versionsnummer  im  BCD-Format,  also
  82.                0x0100 für 1.00.
  83.  
  84. config.
  85.        onoff   Über  dieses Bit wird Selectric™ ein (logisch  1)  bzw.
  86.                ausgeschaltet.
  87.        hidden  Zeigt an,  ob versteckte Dateien angezeigt werden  sol-
  88.                len.
  89.        dclick  Ordner erst auf Doppelklick öffnen.
  90.        lower   Pfadangaben etc.  in der Hauptseite in  Kleinbuchstaben
  91.                anzeigen.
  92.        numsrt  Schaltet die numerische Sortierung ein.
  93.        autloc  Aktiviert den Auto-Locator.
  94.        stdest  Nach Kopier/Verschiebe-Aktionen im Zielpfad bleiben.
  95.        pthsav  Ist  dieses Flag gesetzt,  so speichert Selectric™  die
  96.                GEMDOS-Pfade  und stellt sie kurz vor Verlassen  wieder
  97.                her.
  98.  
  99. sort           Konfiguriert  das Sortierkriterium,  dabei gelten  fol-
  100.                gende Werte:
  101.  
  102.                1    Sortiert nach dem Namen
  103.                2    nach Datum
  104.                3    nach Größe
  105.                4    nach Typ bzw. Extension
  106.                5    unsortiert
  107.  
  108.                Ist der Wert negativ,  so wird rückwärts sortiert (z.B.
  109.                -3 für `nach Größe' und `rückwärts').
  110.  
  111. num_ext        Dieser  Wert  gibt  die Anzahl  der  möglichen  Preset-
  112.                Extensions  an.  Wird von der Applikation  eine  andere
  113.                Anzahl  von Extensions übergeben,  so muß  dieser  Wert
  114.                angepaßt werden.  Selectric™ V1.0 verarbeitet z.Zt. nur
  115.                10 Extensions,  werden mehr übergeben, so wird der Wert
  116.                von Selectric™ aus auf 10 reduziert.
  117.  
  118. *(*ext)[]      Dieser  Zeiger  zeigt  auf ein Array  aus  Zeigern  auf
  119.                Strings.   In   diesen  Strings  stehen   die   Preset-
  120.                Extensions.   Wird  der  Pointer  von  der  Applikation
  121.                verändert,  so  muß er auf eine  gleichartige  Struktur
  122.                zeigen.  Der  Zeiger  (und auch die  Anzahl)  wird  von
  123.                Selectric™ aus wieder zurückgesetzt.
  124.  
  125. num_paths      Gibt  die Anzahl der Preset-Paths an  (ansonsten  siehe
  126.                `num_ext').
  127.  
  128. *(*paths)[]    Das  ist für die Preset-Paths  da  (s.a.  `*(*ext)[]').
  129.                Bemerkung:  Das  übergeben von Pfaden  sollte  wirklich
  130.                nur  dann angewendet werden,  wenn dies  auch  sinnvoll
  131.                erscheint.  Weiterhin  sollte man diese Pfade  auch  in
  132.                der  Applikation abspeichern können  (Selectric™  spei-
  133.                chert  nur seine eigenen Extensions/Paths ab,  die  von
  134.                der   Applikation  übergebenen  können  aber   trotzdem
  135.                editiert werden!).
  136.  
  137. comm           Dieses Wort wird zur Kommunikation zwischen  Selectric™
  138.                und der Applikation benutzt. Es wird nach Verlassen von
  139.                Selectric™ automatisch auf Null zurückgesetzt. Zur Zeit
  140.                wird   nur  die  Richtung  Applikation  ->   Selectric™
  141.                unterstützt.   Die   einzelnen  Bits   haben   folgende
  142.                Bedeutung:
  143.  
  144.                Bit 0     Das   Programm   erwartet  mehr   als   einen
  145.                          Dateinamen (s.a.  *out_ptr).  Dabei wird  die
  146.                          gleiche  Struktur wie bei `paths'  und  `ext'
  147.                          erwartet.  Ordner werden mit einem  Backslash
  148.                          am Ende gekennzeichnet.
  149.                Bit 1     Dieses Bit gilt nur in Verbindung mit Bit  0.
  150.                          Ist   das  Bit  gesetzt,   dann  werden   die
  151.                          Dateinamen  durch  Leerzeichen  als  einziger
  152.                          String  zurückgegeben,  fast so wie wenn  man
  153.                          einem  Programm eine Kommandozeile  übergeben
  154.                          würde.  Auch  hier sind die Ordner mit  einem
  155.                          Backslash am Ende gekennzeichnet.
  156.  
  157.                Die  anderen Bits sind resrviert und  sollten  (besser:
  158.                dürfen) nicht verändert bzw. benutzt werden.
  159.  
  160. in_count       z.Zt. unbenutzt
  161.  
  162. *in_ptr        z.Zt. unbenutzt
  163.  
  164. out_count      Die Applikation benutzt es, um anzugeben wieviele Items
  165.                zurückgegeben werden sollen.  Selectric™ schreibt  kurz
  166.                vor dem Verlassen die tatsächliche Anzahl rein.
  167.  
  168. *out_ptr       Dieser   Pointer   muß   bei   Benutzung   auf    einen
  169.                Speicherbereich  bzw.  Struktur,  welche innerhalb  der
  170.                Applikation alloziert wurde, zeigen. Wichtig ist dabei,
  171.                daß genügend Speicher alloziert wurde!
  172.  
  173.  
  174. Seit  Version 1.02 gibt es auch noch drei neue Funktionen,  mit  denen
  175. man  noch  auf  eine  andere Art  und  Weise  mehrere  Dateinamen  zu-
  176. rückbekommen kann.  Sie arbeiten nach dem First/Next-Prinzip und haben
  177. den  Vorteil,  daß  die Hauptapplikation keinen Speicher für  die  Da-
  178. teiliste  zur Verfügung stellen muß.  Sie arbeiten äquivalent  zu  den
  179. TOS-Routinen Fsfirst() und Fsnext(),  mit dem kleinen Unterschied, daß
  180. man jeweils einen Zeiger auf eine DTA-Struktur übergeben  muß.  Ebenso
  181. kann  man  bei  get_first() keine Dateimuster  übergeben,  da  das  ja
  182. eigentlich  der User im Selector macht.  Weiterhin muß nach dem  Holen
  183. der  Dateinamen release_dir() aufgerufen werden,  damit Selectric  den
  184. Speicher  wieder  freigibt.  Die ganze Aktion  muß  mit  wind_update()
  185. eingeschachtelt werden, da es sonst zu Reentranzproblemen in Selectric
  186. kommen kann.
  187.  
  188.  
  189. Bemerkung:     Die  Struktur ist in den Grundzügen kompatibel  zu  der
  190.                aus FSELECT 1.2.x von Martin Patzel/Köhling,  d.h.  ID,
  191.                Versionsnummer und das ON/OFF Bit sind an der  gleichen
  192.                Stelle  zu  finden.  Der  Rest  ist  natürlich  nur  in
  193.                Selectric™ vorhanden.
  194.  
  195.  
  196. Nach dem Motto `ein Programm sagt mehr als tausend Worte' verweise ich
  197. an dieser Stelle auf das Beispielprogramm und das Binding.
  198.  
  199.  
  200. Nachwort
  201. --------
  202. Bleibt  nur noch zu sagen,  daß noch einiges geplant ist,  welches  in
  203. späteren  Versionen  auch verwirklicht wird,  jedoch wollten  wir  das
  204. nicht  `übers Knie brechen'.  Aber schon jetzt hat Selectric™ die  um-
  205. fangreichste Programmierschnittstelle in der File-Selektor Welt.
  206. Ach ja,  das Binding und das Sample wurden nicht so intensiv getestet,
  207. jedoch  sollten keine schwerwiegenden Fehler enhalten sein.  Für  Bug-
  208. Reports bin ich aber immer sehr dankbar.
  209.  
  210.  
  211. Meine Adresse ...
  212.  
  213. Oliver Scheel
  214. Rothehausstr. 28
  215. W-5000 Köln 30 (Germany)
  216.  
  217. MausNet:  Oliver Scheel @ K
  218. InterNet: Oliver_Scheel@k.maus.de
  219.  
  220.  
  221. It's not a trick, it's Selectric™.
  222.  
  223.  
  224. ----
  225. Rächzschreipfäler (c) 1992 by Oliver Scheel
  226.